<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        
        <title>
                        The Unicode Chapter
                     &mdash; Mako 0.5.0 Documentation</title>
        
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <link rel="stylesheet" href="_static/docs.css" type="text/css" />

    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
          URL_ROOT:    '#',
          VERSION:     '0.5.0',
          COLLAPSE_MODINDEX: false,
          FILE_SUFFIX: '.html'
      };
    </script>
        <script type="text/javascript" src="_static/jquery.js"></script>
        <script type="text/javascript" src="_static/underscore.js"></script>
        <script type="text/javascript" src="_static/doctools.js"></script>
    <script type="text/javascript" src="_static/init.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="top" title="Mako 0.5.0 Documentation" href="index.html" />
        <link rel="next" title="Caching" href="caching.html" />
        <link rel="prev" title="Filtering and Buffering" href="filtering.html" />

    
    

    </head>
    <body>
        



        <h1>Mako 0.5.0 Documentation</h1>

        <div id="search">
        Search:
        <form class="search" action="search.html" method="get">
          <input type="text" name="q" size="18" /> <input type="submit" value="Search" />
          <input type="hidden" name="check_keywords" value="yes" />
          <input type="hidden" name="area" value="default" />
        </form>
        </div>

        <div class="versionheader">
            Version: <span class="versionnum">0.5.0</span> Last Updated: 09/27/2011 20:26:30
        </div>
        <div class="clearboth"></div>

        <div class="topnav">
            <div id="pagecontrol">
                <a href="genindex.html">Index</a>
 
                <div class="sourcelink">(<a href="_sources/unicode.txt">view source)</div>
            </div>
 
            <div class="navbanner">
                <a class="totoc" href="index.html">Table of Contents</a>
                » 
                        The Unicode Chapter
                     

                
<div class="prevnext">
        Previous:
        <a href="filtering.html" title="previous chapter">Filtering and Buffering</a>
        Next:
        <a href="caching.html" title="next chapter">Caching</a>
</div>

                <h2>
                    
                        The Unicode Chapter
                    
                </h2>
            </div>
                <ul>
<li><a class="reference internal" href="#">The Unicode Chapter</a><ul>
<li><a class="reference internal" href="#specifying-the-encoding-of-a-template-file">Specifying the Encoding of a Template File</a></li>
<li><a class="reference internal" href="#handling-expressions">Handling Expressions</a></li>
<li><a class="reference internal" href="#defining-output-encoding">Defining Output Encoding</a><ul>
<li><a class="reference internal" href="#buffer-selection">Buffer Selection</a></li>
</ul>
</li>
<li><a class="reference internal" href="#saying-to-heck-with-it-disabling-the-usage-of-unicode-entirely">Saying to Heck with it: Disabling the usage of Unicode entirely</a></li>
</ul>
</li>
</ul>

            <div class="clearboth"></div>
        </div>
 
        <div class="document">
            <div class="body">
                
<div class="section" id="the-unicode-chapter">
<span id="unicode-toplevel"></span><h1>The Unicode Chapter<a class="headerlink" href="#the-unicode-chapter" title="Permalink to this headline">¶</a></h1>
<p>The Python language supports two ways of representing what we
know as &#8220;strings&#8221;, i.e. series of characters. In Python 2, the
two types are <tt class="docutils literal"><span class="pre">string</span></tt> and <tt class="docutils literal"><span class="pre">unicode</span></tt>, and in Python 3 they are
<tt class="docutils literal"><span class="pre">bytes</span></tt> and <tt class="docutils literal"><span class="pre">string</span></tt>. A key aspect of the Python 2 <tt class="docutils literal"><span class="pre">string</span></tt> and
Python 3 <tt class="docutils literal"><span class="pre">bytes</span></tt> types are that they contain no information
regarding what <strong>encoding</strong> the data is stored in. For this
reason they were commonly referred to as <strong>byte strings</strong> on
Python 2, and Python 3 makes this name more explicit. The
origins of this come from Python&#8217;s background of being developed
before the Unicode standard was even available, back when
strings were C-style strings and were just that, a series of
bytes. Strings that had only values below 128 just happened to
be <strong>ascii</strong> strings and were printable on the console, whereas
strings with values above 128 would produce all kinds of
graphical characters and bells.</p>
<p>Contrast the &#8220;bytestring&#8221; types with the &#8220;unicode/string&#8221; type.
Objects of this type are created whenever you say something like
<tt class="docutils literal"><span class="pre">u&quot;hello</span> <span class="pre">world&quot;</span></tt> (or in Python 3, just <tt class="docutils literal"><span class="pre">&quot;hello</span> <span class="pre">world&quot;</span></tt>). In this
case, Python represents each character in the string internally
using multiple bytes per character (something similar to
UTF-16). Whats important is that when using the
<tt class="docutils literal"><span class="pre">unicode</span></tt>/<tt class="docutils literal"><span class="pre">string</span></tt> type to store strings, Python knows the
data&#8217;s encoding; its in its own internal format. Whereas when
using the <tt class="docutils literal"><span class="pre">string</span></tt>/<tt class="docutils literal"><span class="pre">bytes</span></tt> type, it does not.</p>
<p>When Python 2 attempts to treat a byte-string as a string, which
means its attempting to compare/parse its characters, to coerce
it into another encoding, or to decode it to a unicode object,
it has to guess what the encoding is. In this case, it will
pretty much always guess the encoding as <tt class="docutils literal"><span class="pre">ascii</span></tt>...and if the
bytestring contains bytes above value 128, you&#8217;ll get an error.
Python 3 eliminates much of this confusion by just raising an
error unconditionally if a bytestring is used in a
character-aware context.</p>
<p>There is one operation that Python <em>can</em> do with a non-ascii
bytestring, and its a great source of confusion: it can dump the
bytestring straight out to a stream or a file, with nary a care
what the encoding is. To Python, this is pretty much like
dumping any other kind of binary data (like an image) to a
stream somewhere. In Python 2, it is common to see programs that
embed all kinds of international characters and encodings into
plain byte-strings (i.e. using <tt class="docutils literal"><span class="pre">&quot;hello</span> <span class="pre">world&quot;</span></tt> style literals)
can fly right through their run, sending reams of strings out to
whereever they are going, and the programmer, seeing the same
output as was expressed in the input, is now under the illusion
that his or her program is Unicode-compliant. In fact, their
program has no unicode awareness whatsoever, and similarly has
no ability to interact with libraries that <em>are</em> unicode aware.
Python 3 makes this much less likely by defaulting to unicode as
the storage format for strings.</p>
<p>The &#8220;pass through encoded data&#8221; scheme is what template
languages like Cheetah and earlier versions of Myghty do by
default. Mako as of version 0.2 also supports this mode of
operation when using Python 2, using the &#8220;disable_unicode=True&#8221;
flag. However, when using Mako in its default mode of
unicode-aware, it requires explicitness when dealing with
non-ascii encodings. Additionally, if you ever need to handle
unicode strings and other kinds of encoding conversions more
intelligently, the usage of raw bytestrings quickly becomes a
nightmare, since you are sending the Python interpreter
collections of bytes for which it can make no intelligent
decisions with regards to encoding. In Python 3 Mako only allows
usage of native, unicode strings.</p>
<p>In normal Mako operation, all parsed template constructs and
output streams are handled internally as Python <tt class="docutils literal"><span class="pre">unicode</span></tt>
objects. Its only at the point of <a class="reference internal" href="usage.html#mako.template.Template.render" title="mako.template.Template.render"><tt class="xref py py-meth docutils literal"><span class="pre">render()</span></tt></a> that this unicode
stream may be rendered into whatever the desired output encoding
is. The implication here is that the template developer must
ensure that the encoding of all non-ascii templates is explicit
(still required in Python 3), that all non-ascii-encoded
expressions are in one way or another converted to unicode (not
much of a burden in Python 3), and that the output stream of the
template is handled as a unicode stream being encoded to some
encoding (still required in Python 3).</p>
<div class="section" id="specifying-the-encoding-of-a-template-file">
<h2>Specifying the Encoding of a Template File<a class="headerlink" href="#specifying-the-encoding-of-a-template-file" title="Permalink to this headline">¶</a></h2>
<p>This is the most basic encoding-related setting, and it is
equivalent to Python&#8217;s &#8220;magic encoding comment&#8221;, as described in
<a class="reference external" href="http://www.python.org/dev/peps/pep-0263/">pep-0263</a>. Any
template that contains non-ascii characters requires that this
comment be present so that Mako can decode to unicode (and also
make usage of Python&#8217;s AST parsing services). Mako&#8217;s lexer will
use this encoding in order to convert the template source into a
<tt class="docutils literal"><span class="pre">unicode</span></tt> object before continuing its parsing:</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="cp">## -*- coding: utf-8 -*-</span><span class="x"></span>

<span class="x">Alors vous imaginez ma surprise, au lever du jour, quand</span>
<span class="x">une drôle de petite voix m’a réveillé. Elle disait:</span>
<span class="x"> « S’il vous plaît… dessine-moi un mouton! »</span>
</pre></div>
</div>
<p>For the picky, the regular expression used is derived from that
of the abovementioned pep:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c">#.*coding[:=]\s*([-\w.]+).*\n</span>
</pre></div>
</div>
<p>The lexer will convert to unicode in all cases, so that if any
characters exist in the template that are outside of the
specified encoding (or the default of <tt class="docutils literal"><span class="pre">ascii</span></tt>), the error will
be immediate.</p>
<p>As an alternative, the template encoding can be specified
programmatically to either <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> or <a class="reference internal" href="usage.html#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><tt class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></tt></a> via
the <tt class="docutils literal"><span class="pre">input_encoding</span></tt> parameter:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">t</span> <span class="o">=</span> <span class="n">TemplateLookup</span><span class="p">(</span><span class="n">directories</span><span class="o">=</span><span class="p">[</span><span class="s">&#39;./&#39;</span><span class="p">],</span> <span class="n">input_encoding</span><span class="o">=</span><span class="s">&#39;utf-8&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>The above will assume all located templates specify <tt class="docutils literal"><span class="pre">utf-8</span></tt>
encoding, unless the template itself contains its own magic
encoding comment, which takes precedence.</p>
</div>
<div class="section" id="handling-expressions">
<h2>Handling Expressions<a class="headerlink" href="#handling-expressions" title="Permalink to this headline">¶</a></h2>
<p>The next area that encoding comes into play is in expression
constructs. By default, Mako&#8217;s treatment of an expression like
this:</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="cp">${</span><span class="s">&quot;hello world&quot;</span><span class="cp">}</span><span class="x"></span>
</pre></div>
</div>
<p>looks something like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">context</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="nb">unicode</span><span class="p">(</span><span class="s">&quot;hello world&quot;</span><span class="p">))</span>
</pre></div>
</div>
<p>In Python 3, its just:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">context</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="nb">str</span><span class="p">(</span><span class="s">&quot;hello world&quot;</span><span class="p">))</span>
</pre></div>
</div>
<p>That is, <strong>the output of all expressions is run through the
``unicode`` builtin</strong>. This is the default setting, and can be
modified to expect various encodings. The <tt class="docutils literal"><span class="pre">unicode</span></tt> step serves
both the purpose of rendering non-string expressions into
strings (such as integers or objects which contain <tt class="docutils literal"><span class="pre">__str()__</span></tt>
methods), and to ensure that the final output stream is
constructed as a unicode object. The main implication of this is
that <strong>any raw bytestrings that contain an encoding other than
ascii must first be decoded to a Python unicode object</strong>. It
means you can&#8217;t say this in Python 2:</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="cp">${</span><span class="s">&quot;voix m’a réveillé.&quot;</span><span class="cp">}</span>  <span class="cp">## error in Python 2!</span><span class="x"></span>
</pre></div>
</div>
<p>You must instead say this:</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="cp">${</span><span class="s">u&quot;voix m’a réveillé.&quot;</span><span class="cp">}</span>  <span class="cp">## OK !</span><span class="x"></span>
</pre></div>
</div>
<p>Similarly, if you are reading data from a file that is streaming
bytes, or returning data from some object that is returning a
Python bytestring containing a non-ascii encoding, you have to
explcitly decode to unicode first, such as:</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="cp">${</span><span class="n">call_my_object</span><span class="p">()</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s">&#39;utf-8&#39;</span><span class="p">)</span><span class="cp">}</span><span class="x"></span>
</pre></div>
</div>
<p>Note that filehandles acquired by <tt class="docutils literal"><span class="pre">open()</span></tt> in Python 3 default
to returning &#8220;text&#8221;, that is the decoding is done for you. See
Python 3&#8217;s documentation for the <tt class="docutils literal"><span class="pre">open()</span></tt> builtin for details on
this.</p>
<p>If you want a certain encoding applied to <em>all</em> expressions,
override the <tt class="docutils literal"><span class="pre">unicode</span></tt> builtin with the <tt class="docutils literal"><span class="pre">decode</span></tt> builtin at the
<a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> or <a class="reference internal" href="usage.html#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><tt class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></tt></a> level:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">t</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="n">templatetext</span><span class="p">,</span> <span class="n">default_filters</span><span class="o">=</span><span class="p">[</span><span class="s">&#39;decode.utf8&#39;</span><span class="p">])</span>
</pre></div>
</div>
<p>Note that the built-in <tt class="docutils literal"><span class="pre">decode</span></tt> object is slower than the
<tt class="docutils literal"><span class="pre">unicode</span></tt> function, since unlike <tt class="docutils literal"><span class="pre">unicode</span></tt> its not a Python
builtin, and it also checks the type of the incoming data to
determine if string conversion is needed first.</p>
<p>The <tt class="docutils literal"><span class="pre">default_filters</span></tt> argument can be used to entirely customize
the filtering process of expressions. This argument is described
in <a class="reference internal" href="filtering.html#filtering-default-filters"><em>The default_filters Argument</em></a>.</p>
</div>
<div class="section" id="defining-output-encoding">
<h2>Defining Output Encoding<a class="headerlink" href="#defining-output-encoding" title="Permalink to this headline">¶</a></h2>
<p>Now that we have a template which produces a pure unicode output
stream, all the hard work is done. We can take the output and do
anything with it.</p>
<p>As stated in the &#8220;Usage&#8221; chapter, both <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> and
<a class="reference internal" href="usage.html#mako.lookup.TemplateLookup" title="mako.lookup.TemplateLookup"><tt class="xref py py-class docutils literal"><span class="pre">TemplateLookup</span></tt></a> accept <tt class="docutils literal"><span class="pre">output_encoding</span></tt> and <tt class="docutils literal"><span class="pre">encoding_errors</span></tt>
parameters which can be used to encode the output in any Python
supported codec:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mako.template</span> <span class="kn">import</span> <span class="n">Template</span>
<span class="kn">from</span> <span class="nn">mako.lookup</span> <span class="kn">import</span> <span class="n">TemplateLookup</span>

<span class="n">mylookup</span> <span class="o">=</span> <span class="n">TemplateLookup</span><span class="p">(</span><span class="n">directories</span><span class="o">=</span><span class="p">[</span><span class="s">&#39;/docs&#39;</span><span class="p">],</span> <span class="n">output_encoding</span><span class="o">=</span><span class="s">&#39;utf-8&#39;</span><span class="p">,</span> <span class="n">encoding_errors</span><span class="o">=</span><span class="s">&#39;replace&#39;</span><span class="p">)</span>

<span class="n">mytemplate</span> <span class="o">=</span> <span class="n">mylookup</span><span class="o">.</span><span class="n">get_template</span><span class="p">(</span><span class="s">&quot;foo.txt&quot;</span><span class="p">)</span>
<span class="k">print</span> <span class="n">mytemplate</span><span class="o">.</span><span class="n">render</span><span class="p">()</span>
</pre></div>
</div>
<p><a class="reference internal" href="usage.html#mako.template.Template.render" title="mako.template.Template.render"><tt class="xref py py-meth docutils literal"><span class="pre">render()</span></tt></a> will return a <tt class="docutils literal"><span class="pre">bytes</span></tt> object in Python 3 if an output
encoding is specified. By default it performs no encoding and
returns a native string.</p>
<p><a class="reference internal" href="usage.html#mako.template.Template.render_unicode" title="mako.template.Template.render_unicode"><tt class="xref py py-meth docutils literal"><span class="pre">render_unicode()</span></tt></a> will return the template output as a Python
<tt class="docutils literal"><span class="pre">unicode</span></tt> object (or <tt class="docutils literal"><span class="pre">string</span></tt> in Python 3):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">print</span> <span class="n">mytemplate</span><span class="o">.</span><span class="n">render_unicode</span><span class="p">()</span>
</pre></div>
</div>
<p>The above method disgards the output encoding keyword argument;
you can encode yourself by saying:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">print</span> <span class="n">mytemplate</span><span class="o">.</span><span class="n">render_unicode</span><span class="p">()</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s">&#39;utf-8&#39;</span><span class="p">,</span> <span class="s">&#39;replace&#39;</span><span class="p">)</span>
</pre></div>
</div>
<div class="section" id="buffer-selection">
<h3>Buffer Selection<a class="headerlink" href="#buffer-selection" title="Permalink to this headline">¶</a></h3>
<p>Mako does play some games with the style of buffering used
internally, to maximize performance. Since the buffer is by far
the most heavily used object in a render operation, its
important!</p>
<p>When calling <a class="reference internal" href="usage.html#mako.template.Template.render" title="mako.template.Template.render"><tt class="xref py py-meth docutils literal"><span class="pre">render()</span></tt></a> on a template that does not specify any
output encoding (i.e. its <tt class="docutils literal"><span class="pre">ascii</span></tt>), Python&#8217;s <tt class="docutils literal"><span class="pre">cStringIO</span></tt> module,
which cannot handle encoding of non-ascii <tt class="docutils literal"><span class="pre">unicode</span></tt> objects
(even though it can send raw bytestrings through), is used for
buffering. Otherwise, a custom Mako class called
<tt class="docutils literal"><span class="pre">FastEncodingBuffer</span></tt> is used, which essentially is a super
dumbed-down version of <tt class="docutils literal"><span class="pre">StringIO</span></tt> that gathers all strings into
a list and uses <tt class="docutils literal"><span class="pre">u''.join(elements)</span></tt> to produce the final output
- its markedly faster than <tt class="docutils literal"><span class="pre">StringIO</span></tt>.</p>
</div>
</div>
<div class="section" id="saying-to-heck-with-it-disabling-the-usage-of-unicode-entirely">
<span id="unicode-disabled"></span><h2>Saying to Heck with it: Disabling the usage of Unicode entirely<a class="headerlink" href="#saying-to-heck-with-it-disabling-the-usage-of-unicode-entirely" title="Permalink to this headline">¶</a></h2>
<p>Some segements of Mako&#8217;s userbase choose to make no usage of
Unicode whatsoever, and instead would prefer the &#8220;passthru&#8221;
approach; all string expressions in their templates return
encoded bytestrings, and they would like these strings to pass
right through. The only advantage to this approach is that
templates need not use <tt class="docutils literal"><span class="pre">u&quot;&quot;</span></tt> for literal strings; there&#8217;s an
arguable speed improvement as well since raw bytestrings
generally perform slightly faster than unicode objects in
Python. For these users, assuming they&#8217;re sticking with Python
2, they can hit the <tt class="docutils literal"><span class="pre">disable_unicode=True</span></tt> flag as so:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># -*- encoding:utf-8 -*-</span>
<span class="kn">from</span> <span class="nn">mako.template</span> <span class="kn">import</span> <span class="n">Template</span>

<span class="n">t</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="s">&quot;drôle de petite voix m’a réveillé.&quot;</span><span class="p">,</span> <span class="n">disable_unicode</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span> <span class="n">input_encoding</span><span class="o">=</span><span class="s">&#39;utf-8&#39;</span><span class="p">)</span>
<span class="k">print</span> <span class="n">t</span><span class="o">.</span><span class="n">code</span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">disable_unicode</span></tt> mode is strictly a Python 2 thing. It is
not supported at all in Python 3.</p>
<p>The generated module source code will contain elements like
these:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># -*- encoding:utf-8 -*-</span>
<span class="c">#  ...more generated code ...</span>

<span class="k">def</span> <span class="nf">render_body</span><span class="p">(</span><span class="n">context</span><span class="p">,</span><span class="o">**</span><span class="n">pageargs</span><span class="p">):</span>
    <span class="n">context</span><span class="o">.</span><span class="n">caller_stack</span><span class="o">.</span><span class="n">push_frame</span><span class="p">()</span>
    <span class="k">try</span><span class="p">:</span>
        <span class="n">__M_locals</span> <span class="o">=</span> <span class="nb">dict</span><span class="p">(</span><span class="n">pageargs</span><span class="o">=</span><span class="n">pageargs</span><span class="p">)</span>
        <span class="c"># SOURCE LINE 1</span>
        <span class="n">context</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&#39;dr</span><span class="se">\xc3\xb4</span><span class="s">le de petite voix m</span><span class="se">\xe2\x80\x99</span><span class="s">a r</span><span class="se">\xc3\xa9</span><span class="s">veill</span><span class="se">\xc3\xa9</span><span class="s">.&#39;</span><span class="p">)</span>
        <span class="k">return</span> <span class="s">&#39;&#39;</span>
    <span class="k">finally</span><span class="p">:</span>
        <span class="n">context</span><span class="o">.</span><span class="n">caller_stack</span><span class="o">.</span><span class="n">pop_frame</span><span class="p">()</span>
</pre></div>
</div>
<p>Where above that the string literal used within <a class="reference internal" href="runtime.html#mako.runtime.Context.write" title="mako.runtime.Context.write"><tt class="xref py py-meth docutils literal"><span class="pre">Context.write()</span></tt></a>
is a regular bytestring.</p>
<p>When <tt class="docutils literal"><span class="pre">disable_unicode=True</span></tt> is turned on, the <tt class="docutils literal"><span class="pre">default_filters</span></tt>
argument which normally defaults to <tt class="docutils literal"><span class="pre">[&quot;unicode&quot;]</span></tt> now defaults
to <tt class="docutils literal"><span class="pre">[&quot;str&quot;]</span></tt> instead. Setting default_filters to the empty list
<tt class="docutils literal"><span class="pre">[]</span></tt> can remove the overhead of the <tt class="docutils literal"><span class="pre">str</span></tt> call. Also, in this
mode you <strong>cannot</strong> safely call <a class="reference internal" href="usage.html#mako.template.Template.render_unicode" title="mako.template.Template.render_unicode"><tt class="xref py py-meth docutils literal"><span class="pre">render_unicode()</span></tt></a> - you&#8217;ll get
unicode/decode errors.</p>
<p>The <tt class="docutils literal"><span class="pre">h</span></tt> filter (html escape) uses a less performant pure Python
escape function in non-unicode mode (note that in versions prior
to 0.3.4, it used cgi.escape(), which has been replaced with a
function that also escapes single quotes). This because
MarkupSafe only supports Python unicode objects for non-ascii
strings.</p>
<p><strong>Rules for using disable_unicode=True</strong></p>
<ul class="simple">
<li>don&#8217;t use this mode unless you really, really want to and you
absolutely understand what you&#8217;re doing</li>
<li>don&#8217;t use this option just because you don&#8217;t want to learn to
use Unicode properly; we aren&#8217;t supporting user issues in this
mode of operation. We will however offer generous help for the
vast majority of users who stick to the Unicode program.</li>
<li>Python 3 is unicode by default, and the flag is not available
when running on Python 3.</li>
</ul>
</div>
</div>

            </div>
        </div>

        
            <div class="bottomnav">
                
<div class="prevnext">
        Previous:
        <a href="filtering.html" title="previous chapter">Filtering and Buffering</a>
        Next:
        <a href="caching.html" title="next chapter">Caching</a>
</div>

                <div class="doc_copyright">
                    &copy; Copyright the Mako authors and contributors.
                    Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
                </div>
            </div>
        





    </body>
</html>



